home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / util / libs / cwrlib31.lha / README < prev    next >
Text File  |  1992-07-22  |  13KB  |  320 lines
  1.  
  2.         --------------------------------------------------------------
  3.  
  4.  
  5.                              CWRITE.LIBRARY v1.31
  6.  
  7.                         Programmed by   :  Per Hansen
  8.                         Original code by:  Lars Dam & Per Hansen
  9.  
  10.              (C)opyright 1992 by Tribune Channel Software Team.
  11.                             All rights reserved.
  12.  
  13.        --------------------------------------------------------------
  14.  
  15.                                Cwrite.library
  16.  
  17. A  library that makes it possible to make terminal programs without having to
  18. bother   about   opening  console.device,  IOrequests  etc.   for  outputting
  19. characters to the screen.
  20. It  can write text to a more specific window, and is capable of handling ANSI
  21. escape  sequences,  although this sequence might be interruptet in the middle
  22. of it, and resumed later on..! - Now, THIS is something!
  23. It has faster output than the console.device, even if console.device has been
  24. opened  on  a  2-bitplane  screen and cwrite.library uses a screen with THREE
  25. bitplanes!
  26. It  has  lightning  fast scrolling routines, which only is slowed down if you
  27. use  the  library  on  a screen with 4 bitplanes..  - Much faster ANSI escape
  28. sequence handling, than anything else seen on the Amiga!!
  29. A  little  note:  Actually Lars Dam hasn't seen the source codes since a very
  30. long time ago (don't even remember when), and he would possibly not recognize
  31. it,  but  he  was  the  one  that  made  it possible to make this library, so
  32. therefore i have put his name in top of this file.
  33.  
  34.        --------------------------------------------------------------
  35.  
  36.                                 INTRODUCTION
  37.  
  38. The cwrite.library is released to the public as FREEWARE.
  39. It  may not be included in any commercial package without the authors written
  40. permission,  and  if  it goes into any PD library anywhere over the world, no
  41. charge, except from reasonable media costs, may be taken!
  42.  
  43. Cwrite.library  has  made it possible to make very fast terminal programs, as
  44. it supports most of the standard VT100 escape sequences (also known as ANSI),
  45. including the ones the standard console.device doesn't support.
  46. The only ones not supported by this library, is the 'feedback' stuff, used
  47. on some bulletin boards, that reports the terminal equipment status.
  48.  
  49. It  is  capable  of  showing  characters  that  are not normally visible on a
  50. standard  console.device  opened  window.  (I.e.  Danish, Norwegian, Swedish,
  51. German, etc. characters.)
  52.  
  53.        --------------------------------------------------------------
  54.  
  55.                                   CONTENTS
  56.  
  57. This archive, "CwrLib31.LHA" contains the following sixteen files:
  58.  
  59.  Filename            Bytes     Description
  60. ------------------- ------- -----------------------------------------------
  61.  Changes_V131.txt     1055  -- Changes from prior release.
  62.  cwrite.doc           9034  -- The Autodocs for cwrite.library
  63.  cwrite.library       4992  -- The cwrite.library. Put it in your LIBS: drawer
  64.  CWrite.fd             261  -- FD file for the library.
  65.  cwritelib.h          2473  -- C-include file for the library routines.
  66.  cwritelib.i          2404  -- ASM-include file.
  67.  cwritelibbase.h       807  -- C-include file for the library base definition
  68.  cwritelibbase.i      1305  -- ASM-include file.
  69.  README              12652  -- The documentation file (you're reading it!).
  70.  Testlib              2972  -- Program, showing how to program the library.
  71.  Testlib.c            3808  -- Sources for the program.
  72.  EAGLE.ANS            3166  -- Example file containing ANSI escape sequences.
  73.  SAGA.ANS            10598  --  do.
  74.  ANSITEST.ANS         2415  --  do.
  75.  
  76.  CWTerm/CWTerm        7536  -- Sample communications program using cwrite.
  77.  CWTerm/CWTerm.c     10625  -- Sources for the above..
  78.  CWTerm/CWTermwin.c   3939  --  do.
  79.  CWTerm/comserial.c   5904  --  do.
  80.  
  81. *PLEASE* don't remove ANY of these files from the archive if you intend to
  82. redistribute this file to other BBS's. I have spent a lot of time creating
  83. all of these files, and I would like them to be kept together in the
  84. *original* archive that I originally distributed! Thanks!
  85.  
  86. The  library  itself, however, may be distributed together with programs that
  87. use  this  library.   - I would, however, prefere that the cwrite.doc and the
  88. include files always follows the library.
  89.  
  90.        --------------------------------------------------------------
  91.  
  92.                            INSTALLATION AND USAGE
  93.  
  94. Before using the library routines, you have to move the library to your
  95. LIBS: drawer on your system disk.
  96.  
  97. Within  this  package,  is  a  test  program with sources, that shows how the
  98. library may be programmed..
  99.  
  100. Any  font  size  should  work together with this library, although fonts with
  101. proportional  sizes  will not show off in the right way, and should therefore
  102. be avoided when using this library.
  103.  
  104. Please read the 'cwrite.doc' for further information on the available library
  105. commands for your applications/programs.
  106.  
  107.        --------------------------------------------------------------
  108.  
  109.                             VT100 MODE SUPPORTED
  110.  
  111. In  order  to  be  able to use cwrite.library in more communication programs,
  112. many VT100 escape sequences are supported by the library.
  113.  
  114. An escape sequence is a sequence of one or more ASCII graphic characters
  115. preceded by the character ESC($1B). For example,
  116.  
  117. ESCc
  118.  
  119. is an escape sequence that causes all setup parameters to be replaced with
  120. the default startup values, and emulates the VT100 hard terminal reset(RIS).
  121. Escape sequences use only 7-bit characters, and can be used in 7-bit or 8-bit
  122. environments.
  123.  
  124. The following escape sequences are supported by cwrite.library:
  125.  
  126.     ESC c       Emulates hard terminal reset.
  127.                 Resets all parameters (except cursortype) to default values.
  128.  
  129.     ESC D       Index (IND). See under control codes below.
  130.  
  131.     ESC E       Next line (NEL). See under control codes below.
  132.  
  133.     ESC M       Reverse index (RI). See under control codes below.
  134.  
  135.     ESC [       Control sequence introducer (CSI).
  136.  
  137.  
  138. A control sequence is a sequence of one or more ASCII graphic characters
  139. preceded by ESC[ or CSI($9B).
  140. So you can express all control sequences as escape sequences whose second
  141. character code is [. For example, the following sequence cause the current
  142. line of text to be erased.
  143.  
  144. ESC[2K
  145.  
  146. The CSI character has been omitted to make room for more compatibility with
  147. foreign character sets like the danish, norwegian, swedish etc.
  148. CSI, however, can also only be used in an 8-bit environment.
  149.  
  150. The following VT100 control sequences are supported by cwrite.library:
  151.  
  152.     ESC[xA      Cursor up by x lines in the same column. Default 1.
  153.  
  154.     ESC[xB      Cursor down x lines in the same column. Default 1.
  155.  
  156.     ESC[xC      Cursor right by x columns. Default 1.
  157.  
  158.     ESC[xD      Cursor left by x columns. Default 1.
  159.  
  160.     ESC[x;yH    Moves cursor to line x column y. One or both of the
  161.                 arguments can be omitted, e.g. to move to column 0
  162.                 line 10, ESC[10;H will do.
  163.  
  164.     ESC[x;yf    Moves cursor to line x column y. One or both of the
  165.                 arguments can be omitted, e.g. to move to column 0
  166.                 line 10, ESC[10;f will do.
  167.  
  168.     ESC[x;..;ym Select Graphic Rendition (SGR)
  169.  
  170.                 You can select one or more character renditions at a time
  171.                 using the following format:
  172.  
  173.                 ESC[Ps;...Psm
  174.  
  175.                 When you use multiple parameters they are executed in
  176.                 sequence. The effects are cumulative. For example, to change
  177.                 from increased intensity (or bold) to italic-underlined, you
  178.                 can use:
  179.  
  180.                 ESC[0;4;5m
  181.  
  182.                 When you select a single parameter, no delimiter (';') is
  183.                 used.
  184.  
  185.                 Ps      Action
  186.  
  187.                 0       All attributes off.
  188.                 1       Display bold, or at increased intensity if 4 bitplanes
  189.                 3       Display italic
  190.                 4       Display underscored
  191.                 5       Display italic  (Amiga-ized "blinking")
  192.                 7       Display negative (reverse) image.
  193.                 2   1   Display normal intensity
  194.                 2   3   Display not italic
  195.                 2   4   Display not underlined
  196.                 2   5   Display not italic
  197.                 2   7   Display positive image
  198.  
  199.                 The same sequence is used to change the color of
  200.                 the current pen. Colors used by the library are:
  201.  
  202.                 30/40   Black (Standard background)
  203.                 31/41   Red
  204.                 32/42   Green
  205.                 33/43   Yellow
  206.                 34/44   Blue
  207.                 35/45   Purple
  208.                 36/46   Cyan
  209.                 37/47   White (Standard foreground)
  210.  
  211.                 To write the words 'Hello world' in green on cyan background
  212.                 you can use:
  213.  
  214.                 ESC[32;46mHello worldESC[0m
  215.  
  216.                 The color codes can also be used in combination with the
  217.                 graphic rendition, so that you can get 'Hello world' printed
  218.                 in cyan on green background by using the display negative
  219.                 image:
  220.  
  221.                 ESC[7;32;46mHello worldESC[0m
  222.  
  223.     ESC[xL      Inserts x lines at the cursor. Default 1.
  224.  
  225.     ESC[xM      Deletes x lines starting at the lines with the cursor.
  226.                 Default 1.
  227.  
  228.     ESC[xP      Deletes x characters starting with the character at the
  229.                 cursor position. Default 1.
  230.  
  231.     ESC[K       Erases from the cursor to the end of the line, including
  232.                 the cursor position.
  233.  
  234.     ESC[0K      Same as the above.
  235.  
  236.     ESC[1K      Erases from the beginning of the line to the cursor,
  237.                 including the cursor position.
  238.  
  239.     ESC[2K      Erases the complete line.
  240.  
  241.     ESC[J       Erases from the cursor to the end of the screen, including
  242.                 the cursor position.
  243.  
  244.     ESC[0J      Same as the above.
  245.  
  246.     ESC[1J      Erases from the beginning of the screen to the cursor,
  247.                 including the cursor position.
  248.  
  249.     ESC[2J      Erases the complete display.
  250.  
  251.     ESC[s       Saves in memory the current cursor position.
  252.  
  253.     ESC[u       Restores the current cursor position from memory.
  254.                 If cursor has not been previously saved, the cursor
  255.                 will be put at the upper left corner of the screen.
  256.  
  257.  
  258. The following control codes are supported by the cwrite.library:
  259.  
  260.     ASCII       Action
  261.  
  262.     7           Bell (BEL)
  263.                 Calls DisplayBeep to flash the screen.
  264.  
  265.     8           BackSpace (BS).
  266.                 Moves cursor to the left one character position, if cursor
  267.                 is at left magin it continues at the right border at the
  268.                 line above.
  269.  
  270.     9           Tabulator (TAB).
  271.                 Moves cursor to the next tab stop. Currently tab stops are
  272.                 every 8 characters. Does not cause autowrap.
  273.  
  274.     10          LineFeed (LF).
  275.                 Causes a linefeed operation.
  276.  
  277.     11          Vertical tabulation (VT)
  278.                 Processed as LF.
  279.  
  280.     12          Form Feed (FF).
  281.                 Clears the screen.
  282.  
  283.     13          Carriage Return (CR).
  284.                 Moves cursor to left margin on current line.
  285.  
  286.     132         Index (IND).
  287.                 Moves cursor down one line in the same column.
  288.                 If cursor is at bottom margin, screen performs a
  289.                 scroll up.
  290.  
  291.     133         Next line (NEL).
  292.                 Moves cursor to first position on next line.
  293.                 If cursor is at bottom margin, screen performs a
  294.                 scroll up.
  295.  
  296.     140         Reverse index (RI).
  297.                 Moves cursor up one line in same column.
  298.                 If cursor is at top margin, screen performs a
  299.                 scroll down.
  300.  
  301.        --------------------------------------------------------------
  302.  
  303.                                  KNOWN BUGS
  304.  
  305. I  have  discovered,  that the CURSORTYPE_FAST may not work properly together
  306. with  an  interlaced  screen,  and  should therefore only be used on a normal
  307. display (non-interlaced) screen.
  308. -  This  bug will _not_ be fixed, and therefore the CURSORTYPE_FAST should be
  309. avoided, using the CURSORTYPE_SLOW instead.
  310. -  The CURSORTYPE_SLOW routines has been heavily improved until this release,
  311. and there is only very little difference in the speed, so why worry?
  312.  
  313.        --------------------------------------------------------------
  314.  
  315.                              WHERE TO CONTACT ME
  316.  
  317. You can contact me on the following Bulletin Board or FidoNet Address
  318.  
  319. Per Hansen, SAGA AmigaBBS +45 3116 3217  (2:231/84.0) (Denmark)
  320.